Signature: pd.asof_merge(left, right, on=None, left_on=None, right_on=None, by=None, suffixes=('_x', '_y'), tolerance=None, allow_exact_matches=True)
Docstring:
Perform an asof merge. This by definition will fill the right data with
the asof the left data. The data must be ordered according to the 'on'
(typically time). Optionally perform group-wise merge.

Asof means return the last good (non-NaN) value in object for the date in
question. This is conceptually very close to a left-outer join with
forward filling.

.. versionadded 0.18.2

Parameters
----------
left: DataFrame
right: DataFrame
    Data will be de-duplicated on the [by, on] combination if needed.
on: label or list
    Field names to join on. Must be found in both DataFrames.
    The data MUST be ordered. Furthermore this must be a datetimelike or
    integer-index.
left_on: label or list, or array-like
    Field names to join on in left DataFrame. Can be a vector or list of
    vectors of the length of the DataFrame to use a particular vector as
    the join key instead of columns
right_on: label or list, or array-like
    Field names to join on in right DataFrame or vector/list of vectors per
    left_on docs
by: column name or list of column names
    Group both the left and right DataFrames by the group columns; perform
    the merge operation on these pieces and recombine.
suffixes: 2-length sequence (tuple, list, ...)
    Suffix to apply to overlapping column names in the left and right
    side, respectively
tolerance: integer or Timedelta, optional, default None
    select asof tolerance within this range, must be compatible
    to the merge index.
allow_exact_matches: boolean, default True
    If True, allow matching the same 'on' value (e.g. same time)
    If False, don't match the same 'on' value
        (e.g. don't match the same time)

Returns
-------
merged : DataFrame

Perform an asof merge. This is similar to a left-join except that we match on
nearest key rather than equal keys.

For each row in the left DataFrame, we select the last row in the right DataFrame
whose 'on' key is less than the left's key. Both DataFrames must be sorted by the
key.

Optionally perform group-wise merge. This matches the 'by' key equally, in
addition to the nearest match on the 'on' key.


Parameters
----------
left: DataFrame
right: DataFrame
    Data will be de-duplicated on the [by, on] combination if needed.
on: label or list
    Field names to join on. Must be found in both DataFrames.
    The data MUST be ordered. Furthermore this must be a datetimelike or
    integer-index.
left_on: label or list, or array-like
    Field names to join on in left DataFrame. Can be a vector or list of
    vectors of the length of the DataFrame to use a particular vector as
    the join key instead of columns
right_on: label or list, or array-like
    Field names to join on in right DataFrame or vector/list of vectors per
    left_on docs
by: column name or list of column names
    Group both the left and right DataFrames by the group columns; perform
    the merge operation on these pieces and recombine.
suffixes: 2-length sequence (tuple, list, ...)
    Suffix to apply to overlapping column names in the left and right
    side, respectively
tolerance: integer or Timedelta, optional, default None
    select asof tolerance within this range; must be compatible
    to the merge index.
allow_exact_matches: boolean, default True
    If True, allow matching the same 'on' value (i.e. less-than-or-equal-to)
    If False, don't match the same 'on' value
        (i.e., stricly less-than)

In [1]: df1 = pd.DataFrame({'key':[1,1,3], 'left_val':[1,2,3]})
   ...: df2 = pd.DataFrame({'key':[1,3,3], 'right_val':[1,2,3]})
   ...:

In [2]: pd.merge_asof(df1, df2, on='key')
Out[2]:
   key  left_val  right_val
0    1         1          1
1    1         2          1
2    3         3          2
3    3         3          3

In [3]: df1 = pd.DataFrame({'key':[1,1,3], 'left_val':[1,2,3]})
   ...: df2 = pd.DataFrame({'key':[1,2,2], 'right_val':[1,2,3]})

In [4]: pd.merge_asof(df1, df2, on='key')
Out[4]:
   key  left_val  right_val
0    1         1          1
1    1         2          1
2    3         3          3

In [5]: pd.merge_asof(df1, df2, on='key')
Out[5]: 
   key  left_val  right_val
0    1         1          1
1    1         2          1
2    3         3          3

In [6]: pd.merge(df1, df2, on='key', how='left')
Out[6]: 
   key  left_val  right_val
0    1         1        1.0
1    1         2        1.0
2    3         3        NaN

In [1]: df1 = pd.DataFrame({'key':[1,1,3], 'by':['a']*3, 'left_val':[1,2,3]})
   ...: df2 = pd.DataFrame({'key':[1,3,3], 'by':['a']*3, 'right_val':[1,2,3]})
   ...:

In [2]: pd.merge_asof(df1, df2, on='key')
Out[2]:
  by_x  key  left_val by_y  right_val
0    a    1         1    a          1
1    a    1         2    a          1
2    a    3         3    a          2
3    a    3         3    a          3

In [3]: pd.merge_asof(df1, df2, on='key', by='by')
Out[3]:
  by  key  left_val  right_val
0  a    1         1          1
1  a    1         2          1
2  a    3         3          3

In [4]: df1 = pd.DataFrame({'key':[1,1,3,5], 'by':['a']*4, 'left_val':[1,2,3,4]})
   ...: df2 = pd.DataFrame({'key':[1,2,2,5,5], 'by':['a']*5, 'right_val':[1,2,3,4,5]})
   ...:

In [5]: pd.merge_asof(df1, df2, on='key')
Out[5]:
  by_x  key  left_val by_y  right_val
0    a    1         1    a          1
1    a    1         2    a          1
2    a    3         3    a          3
3    a    5         4    a          4
4    a    5         4    a          5

In [6]: pd.merge_asof(df1, df2, on='key', by='by')
Out[6]:
  by  key  left_val  right_val
0  a    1         1          1
1  a    1         2          1
2  a    3         3          3
3  a    5         4          5

In [7]: pd.merge_asof(df1, df2, on='key', by='by', check_duplicates=False)
Out[7]:
  by  key  left_val  right_val
0  a    1         1          1
1  a    1         2          1
2  a    3         3          3
3  a    5         4          4
4  a    5         4          5